CSS Architecture and Design System

**Referenced Files in This Document** - [main.css](file://src/assets/css/main.css) - [01-variables-reset.css](file://src/assets/css/modules/01-variables-reset.css) - [02-global-utilities.css](file://src/assets/css/modules/02-global-utilities.css) - [38-material-design-3-theme-toggle.css](file://src/assets/css/modules/38-material-design-3-theme-toggle.css) - [39-material-design-3-theme-toggle-complete.css](file://src/assets/css/modules/39-material-design-3-theme-toggle-complete.css) - [40-iaa-alliance-page-light-dark-mode.css](file://src/assets/css/modules/40-iaa-alliance-page-light-dark-mode.css) - [08-carousel-shared-infrastructure.css](file://src/assets/css/modules/08-carousel-shared-infrastructure.css) - [18-about-page.css](file://src/assets/css/modules/18-about-page.css) - [25-responsive-tablet-max-width-1024px.css](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css) - [44-knowledge-base.css](file://src/assets/css/modules/44-knowledge-base.css) - [16-contact-form.css](file://src/assets/css/modules/16-contact-form.css) - [42-newsletter-signup-component.css](file://src/assets/css/modules/42-newsletter-signup-component.css) - [15-cta-section.css](file://src/assets/css/modules/15-cta-section.css) - [material-design-3-main-theme-toggle.js](file://src/assets/js/modules/material-design-3-main-theme-toggle.js) - [theme-toggling.js](file://src/assets/js/modules/theme-toggling.js) - [iaa-alliance-theme-toggle.js](file://src/assets/js/modules/iaa-alliance-theme-toggle.js)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction

This document explains the CSS architecture and design system for a modern, modular, and theme-aware frontend. The system organizes 44 individual style modules with sequential numbering to ensure predictable cascade ordering. It implements a Material Design 3–aligned theming approach with light and dark modes, a cohesive color palette, typography scales, spacing tokens, and component styling patterns. The architecture emphasizes maintainability, performance, and accessibility through CSS custom properties, utility-first classes, and component-scoped styles.

Project Structure

The stylesheet is composed via a single entry that imports 44 modules in a strict order. Each module encapsulates a specific concern: variables, global utilities, components, pages, and responsive breakpoints. This structure ensures predictable cascade and easy maintenance.

graph TB
main["main.css<br/>Imports 44 modules in order"] --> m1["01-variables-reset.css"]
main --> m2["02-global-utilities.css"]
main --> m3["03-custom-cursor.css"]
main --> m4["04-navigation.css"]
main --> m5["05-hero-shared-base.css"]
main --> m6["06-parallax-hero-three-js-scroll-driven-terrain.css"]
main --> m7["07-section-headers-dividers.css"]
main --> m8["08-carousel-shared-infrastructure.css"]
main --> m9["09-services-carousel-homepage.css"]
main --> m10["10-logo-marquee.css"]
main --> m11["11-testimonials-carousel.css"]
main --> m12["12-team-grid-homepage-teaser.css"]
main --> m13["13-news-carousel-homepage.css"]
main --> m14["14-membership-professional-affiliations.css"]
main --> m15["15-cta-section.css"]
main --> m16["16-contact-form.css"]
main --> m17["17-footer.css"]
main --> m18["18-about-page.css"]
main --> m19["19-capabilities-services-overview-page.css"]
main --> m20["20-team-page-full-profiles.css"]
main --> m21["21-cases-page.css"]
main --> m22["22-news-insights-page.css"]
main --> m23["23-document-pages-code-of-conduct-privacy-terms.css"]
main --> m24["24-contact-page.css"]
main --> m25["25-responsive-tablet-max-width-1024px.css"]
main --> m26["26-responsive-mobile-max-width-900px.css"]
main --> m27["27-responsive-small-mobile-max-width-600px.css"]
main --> m28["28-responsive-extra-small-max-width-480px.css"]
main --> m29["29-reduced-motion.css"]
main --> m30["30-service-detail-responsive.css"]
main --> m31["31-footer-utility-classes-referenced-in-rebuilt-pages.css"]
main --> m32["32-news-page-detail-fix-poll-bar-animation-trigger.css"]
main --> m33["33-capabilities-page-responsive-service-detail-rows.css"]
main --> m34["34-contact-page-hero-fix.css"]
main --> m35["35-legal-pages-body-background-fix.css"]
main --> m36["36-iaa-partner-card-logo-placeholder-for-pending-client-assets.css"]
main --> m37["37-iaa-invest-australia-alliance-complete-consolidated-styles.css"]
main --> m38["38-material-design-3-theme-toggle.css"]
main --> m39["39-material-design-3-theme-toggle-complete.css"]
main --> m40["40-iaa-alliance-page-light-dark-mode.css"]
main --> m41["41-search-modal.css"]
main --> m42["42-newsletter-signup-component.css"]
main --> m43["43-mobile-menu-theme-aware-mobile-only.css"]
main --> m44["44-knowledge-base.css"]

Diagram sources

  • [main.css:1-47](file://src/assets/css/main.css#L1-L47)

Section sources

  • [main.css:1-47](file://src/assets/css/main.css#L1-L47)

Core Components

  • Variables and reset: Centralizes design tokens (colors, typography, spacing, transitions) and resets for consistent baseline styling.
  • Global utilities: Provides accessible focus rings, noise overlay, smooth scrolling, and responsive defaults.
  • Material Design 3 theme toggle: Establishes MD3 color roles and elevation tokens, with interactive theme switch UI.
  • Complete theme overrides: Applies comprehensive theme-aware styles across components and pages.
  • Component infrastructure: Shared carousel controls, navigation, and form patterns.
  • Page-specific styles: Dedicated modules for About, Knowledge Base, Contact, and IAA Alliance.
  • Responsive utilities: Breakpoint-specific modules for tablet, mobile, and smaller screens.

Section sources

  • [01-variables-reset.css:1-67](file://src/assets/css/modules/01-variables-reset.css#L1-L67)
  • [02-global-utilities.css:1-64](file://src/assets/css/modules/02-global-utilities.css#L1-L64)
  • [38-material-design-3-theme-toggle.css:1-237](file://src/assets/css/modules/38-material-design-3-theme-toggle.css#L1-L237)
  • [39-material-design-3-theme-toggle-complete.css:1-726](file://src/assets/css/modules/39-material-design-3-theme-toggle-complete.css#L1-L726)
  • [40-iaa-alliance-page-light-dark-mode.css:1-468](file://src/assets/css/modules/40-iaa-alliance-page-light-dark-mode.css#L1-L468)
  • [08-carousel-shared-infrastructure.css:1-90](file://src/assets/css/modules/08-carousel-shared-infrastructure.css#L1-L90)
  • [18-about-page.css:1-144](file://src/assets/css/modules/18-about-page.css#L1-L144)
  • [25-responsive-tablet-max-width-1024px.css:1-333](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css#L1-L333)
  • [44-knowledge-base.css:1-375](file://src/assets/css/modules/44-knowledge-base.css#L1-L375)
  • [16-contact-form.css:1-212](file://src/assets/css/modules/16-contact-form.css#L1-L212)
  • [42-newsletter-signup-component.css:1-235](file://src/assets/css/modules/42-newsletter-signup-component.css#L1-L235)
  • [15-cta-section.css:1-101](file://src/assets/css/modules/15-cta-section.css#L1-L101)

Architecture Overview

The architecture follows a layered approach:

  • Foundation: Variables and reset define the design system’s primitives.
  • Utilities: Global utilities normalize and enhance accessibility.
  • Theming: MD3-aligned theme tokens and theme toggle logic enable seamless light/dark mode.
  • Components: Shared component infrastructure supports consistent behavior across pages.
  • Pages: Page-specific modules apply scoped styles and responsive adaptations.
  • Responsiveness: Breakpoint modules progressively refine layouts.
graph TB
foundation["Variables & Reset<br/>01-variables-reset.css"] --> utilities["Global Utilities<br/>02-global-utilities.css"]
utilities --> theming["MD3 Theme Toggle<br/>38 + 39 modules"]
theming --> components["Component Infrastructure<br/>08 + 15 + 16 + 42 modules"]
components --> pages["Page Styles<br/>18 + 24 + 44 modules"]
pages --> responsive["Responsive Modules<br/>25 + 26 + 27 + 28 + 29 + 30 + 33 + 34 + 35 + 43 modules"]
theming --> iaa["IAA Alliance Theme<br/>40 module"]

Diagram sources

  • [01-variables-reset.css:1-67](file://src/assets/css/modules/01-variables-reset.css#L1-L67)
  • [02-global-utilities.css:1-64](file://src/assets/css/modules/02-global-utilities.css#L1-L64)
  • [38-material-design-3-theme-toggle.css:1-237](file://src/assets/css/modules/38-material-design-3-theme-toggle.css#L1-L237)
  • [39-material-design-3-theme-toggle-complete.css:1-726](file://src/assets/css/modules/39-material-design-3-theme-toggle-complete.css#L1-L726)
  • [40-iaa-alliance-page-light-dark-mode.css:1-468](file://src/assets/css/modules/40-iaa-alliance-page-light-dark-mode.css#L1-L468)
  • [08-carousel-shared-infrastructure.css:1-90](file://src/assets/css/modules/08-carousel-shared-infrastructure.css#L1-L90)
  • [15-cta-section.css:1-101](file://src/assets/css/modules/15-cta-section.css#L1-L101)
  • [16-contact-form.css:1-212](file://src/assets/css/modules/16-contact-form.css#L1-L212)
  • [42-newsletter-signup-component.css:1-235](file://src/assets/css/modules/42-newsletter-signup-component.css#L1-L235)
  • [18-about-page.css:1-144](file://src/assets/css/modules/18-about-page.css#L1-L144)
  • [25-responsive-tablet-max-width-1024px.css:1-333](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css#L1-L333)
  • [44-knowledge-base.css:1-375](file://src/assets/css/modules/44-knowledge-base.css#L1-L375)

Detailed Component Analysis

Design System Foundations

  • Color system: Brand navy, sky blue, red, gold, and neutral backgrounds with HSL-based tokens for consistent gradients and depth.
  • Typography: IBM Plex Sans and serif fonts with a scalable scale and clamp-based hero sizing.
  • Spacing and radii: Consistent spacing tokens and border radius values for rhythm and visual coherence.
  • Elevation and motion: MD3-inspired elevation tokens and transition curves for micro-interactions.
flowchart TD
Start(["Load Variables"]) --> Colors["Brand & Surface Colors<br/>HSL tokens"]
Colors --> Typography["Typography Scale<br/>Base + Clamp Sizing"]
Typography --> Spacing["Spacing & Radius Tokens"]
Spacing --> Elevation["Elevation & Motion Tokens"]
Elevation --> End(["Ready for Theming"])

Diagram sources

  • [01-variables-reset.css:11-64](file://src/assets/css/modules/01-variables-reset.css#L11-L64)

Section sources

  • [01-variables-reset.css:1-67](file://src/assets/css/modules/01-variables-reset.css#L1-L67)

Material Design 3 Theme System

  • MD3 color roles: Primary, surface, onSurface, and outline mapped to brand tokens.
  • Global theme states: body classes toggle light/dark variants with cascading property overrides.
  • Interactive theme switch: Animated toggle with icons, track, handle, and halo effects.
  • Comprehensive overrides: Extensive selectors update navigation, footers, cards, forms, and page-specific elements for both themes.
sequenceDiagram
participant U as "User"
participant DOM as "DOM"
participant JS as "Theme Toggle Script"
participant CSS as "Theme CSS"
U->>DOM : Click theme toggle
DOM->>JS : Event handler
JS->>DOM : Toggle body classes (theme-light/theme-dark)
JS->>DOM : Persist preference in localStorage
DOM->>CSS : Apply theme-specific selectors
CSS-->>U : Visual theme change (colors, shadows, backgrounds)

Diagram sources

  • [material-design-3-main-theme-toggle.js:3-35](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L3-L35)
  • [38-material-design-3-theme-toggle.css:16-33](file://src/assets/css/modules/38-material-design-3-theme-toggle.css#L16-L33)
  • [39-material-design-3-theme-toggle-complete.css:20-205](file://src/assets/css/modules/39-material-design-3-theme-toggle-complete.css#L20-L205)

Section sources

  • [38-material-design-3-theme-toggle.css:1-237](file://src/assets/css/modules/38-material-design-3-theme-toggle.css#L1-L237)
  • [39-material-design-3-theme-toggle-complete.css:1-726](file://src/assets/css/modules/39-material-design-3-theme-toggle-complete.css#L1-L726)
  • [material-design-3-main-theme-toggle.js:1-38](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L1-L38)

IAA Alliance Page Theme

  • Dual theme support: True dark and light variants with dedicated IAA color tokens.
  • Scoped overrides: Ensures navigation, footer, buttons, and content areas adapt appropriately per theme.
  • Theme toggle integration: The page’s theme toggle mirrors the global behavior while respecting IAA branding.
flowchart TD
Init["Init IAA Theme Toggle"] --> LoadPref["Load saved preference"]
LoadPref --> ApplyClass["Apply theme classes to body"]
ApplyClass --> Observe["Observe theme changes"]
Observe --> UpdateSelectors["Update IAA-specific selectors"]
UpdateSelectors --> Persist["Persist new preference"]

Diagram sources

  • [iaa-alliance-theme-toggle.js:3-35](file://src/assets/js/modules/iaa-alliance-theme-toggle.js#L3-L35)
  • [40-iaa-alliance-page-light-dark-mode.css:216-400](file://src/assets/css/modules/40-iaa-alliance-page-light-dark-mode.css#L216-L400)

Section sources

  • [40-iaa-alliance-page-light-dark-mode.css:1-468](file://src/assets/css/modules/40-iaa-alliance-page-light-dark-mode.css#L1-L468)
  • [iaa-alliance-theme-toggle.js:1-38](file://src/assets/js/modules/iaa-alliance-theme-toggle.js#L1-L38)

Component Infrastructure

  • Carousel system: Shared container, navigation buttons, and indicator dots with theme-aware hover states.
  • Contact form: Premium input with floating label, animated highlight, and checkbox styling.
  • CTA section: Gradient background, animated button with scaling pseudo-element, and accessible typography.
  • Newsletter signup: Component with theme-aware inputs, buttons, and responsive layout.
classDiagram
class Carousel {
+container
+navButtons
+dots
}
class ContactForm {
+inputGroup
+floatingLabel
+animatedHighlight
+checkbox
}
class CTASection {
+gradientBackground
+animatedButton
}
class NewsletterSignup {
+themeAwareInputs
+buttons
+responsiveLayout
}
Carousel --> Theme["Theme-aware selectors"]
ContactForm --> Theme
CTASection --> Theme
NewsletterSignup --> Theme

Diagram sources

  • [08-carousel-shared-infrastructure.css:5-90](file://src/assets/css/modules/08-carousel-shared-infrastructure.css#L5-L90)
  • [16-contact-form.css:93-212](file://src/assets/css/modules/16-contact-form.css#L93-L212)
  • [15-cta-section.css:54-101](file://src/assets/css/modules/15-cta-section.css#L54-L101)
  • [42-newsletter-signup-component.css:6-235](file://src/assets/css/modules/42-newsletter-signup-component.css#L6-L235)

Section sources

  • [08-carousel-shared-infrastructure.css:1-90](file://src/assets/css/modules/08-carousel-shared-infrastructure.css#L1-L90)
  • [16-contact-form.css:1-212](file://src/assets/css/modules/16-contact-form.css#L1-L212)
  • [15-cta-section.css:1-101](file://src/assets/css/modules/15-cta-section.css#L1-L101)
  • [42-newsletter-signup-component.css:1-235](file://src/assets/css/modules/42-newsletter-signup-component.css#L1-L235)

Page-Specific Styles

  • About page: Hero sizing, bio sections, diplomacy mosaic, technical split, values film strip, and accordion behavior.
  • Knowledge base: Hero, breadcrumb, tag filtering, card grid, article prose, and theme-aware callouts.
  • Contact page: Dark-themed section with info panel, divider, and form panel.
flowchart TD
About["About Page"] --> Hero["Hero sizing"]
About --> Bio["Bio intro + portraits"]
About --> Diplomacy["Mosaic grid"]
About --> Technical["Split layout"]
About --> Values["Film strip"]
About --> Accordion["Accordion behavior"]
Knowledge["Knowledge Base"] --> HeroK["Hero + breadcrumb"]
Knowledge --> Filter["Tag filter"]
Knowledge --> Cards["Card grid"]
Knowledge --> Article["Article prose + callouts"]
Contact["Contact Page"] --> DarkSection["Dark themed section"]
Contact --> InfoPanel["Info panel"]
Contact --> FormPanel["Form panel"]

Diagram sources

  • [18-about-page.css:6-144](file://src/assets/css/modules/18-about-page.css#L6-L144)
  • [44-knowledge-base.css:6-375](file://src/assets/css/modules/44-knowledge-base.css#L6-L375)
  • [16-contact-form.css:5-100](file://src/assets/css/modules/16-contact-form.css#L5-L100)

Section sources

  • [18-about-page.css:1-144](file://src/assets/css/modules/18-about-page.css#L1-L144)
  • [44-knowledge-base.css:1-375](file://src/assets/css/modules/44-knowledge-base.css#L1-L375)
  • [16-contact-form.css:1-212](file://src/assets/css/modules/16-contact-form.css#L1-L212)

Responsive Utilities

  • Tablet breakpoint: Adjusts navigation to a full-screen mobile menu, carousel card widths, grid layouts, and hero paddings.
  • Additional breakpoints: Mobile, small mobile, extra small, reduced motion, and service-detail-specific tweaks.
flowchart TD
Tablet["Tablet (≤1024px)"] --> Nav["Mobile menu curtain"]
Tablet --> Carousel["Carousel card sizes"]
Tablet --> Grid["Grid adjustments"]
Tablet --> Hero["Hero padding"]
Mobile["Mobile (≤900px)"] --> GridSmall["Smaller grids"]
SmallMobile["Small Mobile (≤600px)"] --> Stack["Stacked layouts"]
ExtraSmall["Extra Small (≤480px)"] --> Compact["Compact spacing"]
ReducedMotion["Reduced Motion"] --> Ease["Reduce motion effects"]

Diagram sources

  • [25-responsive-tablet-max-width-1024px.css:6-333](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css#L6-L333)

Section sources

  • [25-responsive-tablet-max-width-1024px.css:1-333](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css#L1-L333)

Dependency Analysis

The CSS entry imports modules in a strict order to manage cascade and specificity. Theme-related modules depend on variables and utilities, while page modules depend on component infrastructure and theme overrides. Responsive modules depend on earlier modules’ selectors and tokens.

graph LR
Vars["01-variables-reset.css"] --> Utils["02-global-utilities.css"]
Utils --> Theme["38 + 39 theme modules"]
Theme --> Components["08 + 15 + 16 + 42 modules"]
Components --> Pages["18 + 24 + 44 modules"]
Pages --> Responsive["25 + 26 + 27 + 28 + 29 + 30 + 33 + 34 + 35 + 43 modules"]
Theme --> IAA["40-iaa-alliance-page-light-dark-mode.css"]

Diagram sources

  • [main.css:3-46](file://src/assets/css/main.css#L3-L46)

Section sources

  • [main.css:1-47](file://src/assets/css/main.css#L1-L47)

Performance Considerations

  • Modular imports: Keep stylesheets small and focused; only load page-specific modules when needed.
  • Cascade control: Sequential numbering prevents specificity wars and reduces reflows.
  • CSS custom properties: Centralize theme tokens to minimize duplication and improve maintainability.
  • Selective loading: Defer non-critical modules until after initial paint; lazy-load page-specific styles.
  • Specificity management: Prefer component-scoped classes and avoid deep nesting; use utility classes sparingly to prevent bloat.
  • Accessibility: Maintain focus rings and reduced-motion support to improve UX and performance.

Troubleshooting Guide

  • Theme toggle not switching: Verify the presence of the toggle element and that body classes are toggled. Check local storage persistence and keyboard activation.
  • Inconsistent theming in components: Ensure theme-specific selectors are applied after global theme modules and that IAA-specific overrides are included.
  • Navigation conflicts on mobile: Confirm the mobile menu’s clip-path animation and pointer-events are active; check theme-specific overrides for light mode.
  • Carousel visibility issues: Validate that navigation buttons remain visible and that dark-section variants invert button colors.

Section sources

  • [material-design-3-main-theme-toggle.js:3-35](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L3-L35)
  • [iaa-alliance-theme-toggle.js:3-35](file://src/assets/js/modules/iaa-alliance-theme-toggle.js#L3-L35)
  • [25-responsive-tablet-max-width-1024px.css:75-187](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css#L75-L187)
  • [08-carousel-shared-infrastructure.css:13-64](file://src/assets/css/modules/08-carousel-shared-infrastructure.css#L13-L64)

Conclusion

This CSS architecture delivers a robust, modular, and theme-aware design system. Through 44 ordered modules, Material Design 3–aligned theming, and component-scoped styles, the system balances maintainability, performance, and user experience. By leveraging CSS custom properties, utility-first patterns, and progressive responsiveness, teams can confidently evolve the interface while preserving consistency and accessibility.